From e92e54c6460978f3e1b5fc47036c2538faa41a54 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Wed, 25 May 2016 00:55:11 -0400 Subject: [PATCH] Move release notes to online docs This will let us expand the information e.g. with code examples, and can serve as starting material for a future 3->4 migration guide. --- docs/reference/gtk/Makefile.am | 2 + docs/reference/gtk/gtk-docs.sgml | 1 + docs/reference/gtk/migrating-3xtoy.xml | 395 +++++++++++++++++++++++++ 3 files changed, 398 insertions(+) create mode 100644 docs/reference/gtk/migrating-3xtoy.xml diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index 7f6cca75e0..b3c8fc7447 100644 --- a/docs/reference/gtk/Makefile.am +++ b/docs/reference/gtk/Makefile.am @@ -303,6 +303,7 @@ content_files = \ gtk-update-icon-cache.xml \ input-handling.xml \ migrating-2to3.xml \ + migrating-3xtoy.xml \ migrating-checklist.sgml \ migrating-GtkGrid.xml \ migrating-GtkStyleContext.xml \ @@ -329,6 +330,7 @@ expand_content_files = \ glossary.xml \ input-handling.xml \ migrating-2to3.xml \ + migrating-3xtoy.xml \ migrating-checklist.sgml \ migrating-GtkGrid.xml \ migrating-GtkStyleContext.xml \ diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index d091acfc44..d7d96c3056 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -404,6 +404,7 @@ + diff --git a/docs/reference/gtk/migrating-3xtoy.xml b/docs/reference/gtk/migrating-3xtoy.xml new file mode 100644 index 0000000000..074c835ee1 --- /dev/null +++ b/docs/reference/gtk/migrating-3xtoy.xml @@ -0,0 +1,395 @@ + + +]> + + Migrating from one GTK+ 3 release to another + + + GTK+ 3 has seen considerable development over multiple stable releases. + While we try to maintain compatibility as far as possible, some minor + adjustments may be necessary when moving an application from one release + of GTK+ 3 to the next. + + + + The following sections list noteworthy changes in GTK+ 3.x release that + may or may not require applications to be updated. + + +
+ Changes in GTK+ 3.2 + + + The accessible implementations for GTK+ widgets have been integrated + into libgtk itself, and the gail module does not exist anymore. This + change should not affect applications very much. + +
+ +
+ Changes in GTK+ 3.4 + + + Scroll events have been separated from button events, and smooth + scrolling has been added with a separate event mask. Widgets now + need to have either GDK_SCROLL_MASK or GDK_SMOOTH_SCROLL_MASK in + their event mask to receive scroll events. In addition, the + GdkScrollDirection enumeration has gained a new member, + GDK_SCROLL_SMOOTH, so switch statements will have to be amended + to cover this case. + + + + GTK+ now uses <Primary> instead of <Control> in keyboard + accelerators, for improved cross-platform handling. This should not + affect applications, unless they parse or create these accelerator + manually. + + + + The tacit assumption that the Alt key corresponds to the MOD1 + modifier under X11 is now a hard requirement. + + + + The beagle search backend for the file chooser has been dropped. + Tracker is the only supported search backend on Linux now. + + + + GtkNotebook has been changed to destroy its action widgets when + it gets destroyed itself. If your application is using action + widgets in notebooks, you may have to adjust your code to take + this into account. + + + + GtkApplication no longer uses the gtk_ mainloop wrappers, so + it is no longer possible to use gtk_main_quit() to stop it. + + + + The -uninstalled variants of the pkg-config files have been dropped. + + + + Excessive dependencies have been culled from Requires: lines + in .pc files. Dependent modules may have to declare dependencies + that there were getting 'for free' in the past. + +
+ +
+ Changes in GTK+ 3.6 + + + The accessibility bridge code that exports accessible objects + on the bus is now used by default; atk-bridge has been converted + into a library that GTK+ links against. To void the linking, + pass --without-atk-bridge when configuring GTK+. + + + + GDK threading support has been deprecated. It is recommended to + use g_idle_add(), g_main_context_invoke() and similar funtions + to make all GTK+ calls from the main thread. + + + + GTK+ now follows the XDG Base Directory specification for + user configuration and data files. In detail, + + $XDG_CONFIG_HOME/gtk-3.0/custom-papers is the new location + for $HOME/.gtk-custom-papers + $XDG_CONFIG_HOME/gtk-3.0/bookmarks is the new location + for $HOME/.gtk-bookmarks + $XDG_DATA_HOME/themes is preferred over $HOME/.themes + $XDG_DATA_HOME/icons is preferred over $HOME/.icons. + + Existing files from the old location will still be read + if the new location does not exist. + + + + $HOME/.gtk-3.0 is no longer in the default module load path. + If you want to load modules from there, add it to the GTK_PATH + environment variable. + +
+ +
+ Changes in GTK+ 3.8 + + + GtkIconInfo has changed from being a boxed type to a GObject. + This is technically an ABI change, but basically all existing code + will keep working if its used as a boxed type, and it is not + possible to instantiate GtkIconInfos outside GTK+, so this is + not expected to be a big problem. + +
+ +
+ Changes in GTK+ 3.10 + + + GDK has been changed to allow only a single screen per display. + Only the X11 backend had multiple screens before, and multi-screen + setups (not multi-monitor!) are very rare nowadays. If you really + need multiple X screens, open them as separate displays. + + + + The behavior of GtkBox::expand has been changed to never propagate + up. Previously, this was happening inconsistently. If you want the + expand to propagate, use the GtkWidget h/v expand properties. + If you experience sizing problems with widgets in ported code, + carefully check the expand and fill flags of your boxes. + + + + GtkBin no longer provides default implementations for + get_height_for_width, subclasses now have to provide their own + implementation if they need height-for-width functionality. + + + + Widget state propagation has been changed. Historically, all of + active, prelight, selected, insensitive, inconsistent and backdrop + have been propagated to children. This has now been restricted + to just the insensitive and backdrop states. This mostly affects + theming. + + + + The way widget drawing happens has changed. Earlier versions handled + one expose event per GdkWindow, each with a separate cairo_t. Now we + only handle the expose event on the toplevel and reuse the same + cairo_t (with the right translation and clipping) for the entire + widget hierarchy, recursing down via the GtkWidget::draw signal. + Having all rendering in the same call tree allows effects like + opacity and offscreen rendering of entire widget sub-hierarchies. + Generally this should not require any changes in widgets, but + code looking at e.g. the current expose event may see different + behavior than before. + + + + The Gtk+ scrolling implementation has changed. gdk_window_scroll() + and gdk_window_move_region() no longer copy the region on the + window, but rather invalidate the entire scrolled region. This is + slightly slower, but allowed us to implement a offscreen surface + scrolling method which better fits modern hardware. Most scrolling + widgets in Gtk+ have been converted to use this model for scrolling, + but external widgets implementing scrolling using GdkWindow may see + some slowdown. + +
+ +
+ Changes in GTK+ 3.12 + + + GtkWidget had a hack where if opacity is 0.999 we set up an opacity + group when rendering the widget. This is no longer needed in 3.10, + and GtkStack doesn't use it anymore. It has been removed in 3.12. + GdStack is using it, so applications should be ported from GdStack + to GtkStack in 3.12. + + + + GtkHeaderBar in 3.10 was not ordering its pack-end children in + the right way. This has been fixed in 3.12. Applications which + pack multiple widgets at the end of a headerbar will have to + be updated. + + + + gtk_text_view_add_child_in_window has changed behaviour a bit. + It now always positions the child in buffer coordinates, where + it used to inconsistently scroll with the buffer but then go + reposition to a window-relative position on redraw. + + + + A number of container widgets have been made more compliant with + the uniform CSS rendering model by making them render backgrounds + and borders. This may require some adjustments in applications that + were making assumptions about containers never rendering backgrounds. + +
+ +
+ Changes in GTK+ 3.14 + + + A new state, GTK_STATE_FLAG_CHECKED, has been added for checked states + of radio and check buttons and menuitems. Applications that are using + GTK+ styles without widgets will need adjustments. + + + + Adwaita is now the default theme on all platforms. + + + + The icon theme code has become a little pickier about sizes and is not + automatically scaling icons beyond the limits defined in the icon theme + unless explicitly asked to do so with GTK_ICON_LOOKUP_FORCE_SIZE. + + + + GTK+ now includes an interactive debugger which can be activated with + the keyboard shortcuts Ctrl-Shift-d or Ctrl-Shift-i. If these shortcuts + interfere with application keybindings, they can be disabled with the + setting org.gtk.Settings.Debug.enable-inspector-keybinding. + + + + Most widgets have been ported to use the new gesture framework internally + for event handling. Traditional event handlers in derived widgets are still + being called. + + + + Using GTK+ under X11 without the X Render extension has been observed + to be problematic. This combination is using code paths in cairo and + graphics drivers which are rarely tested and likely buggy. + + + + GtkTextView is now using a pixel-cache internally, and is drawing + a background underneath the text. This can cause problems for applications + which assumed that they could draw things below and above the text + by chaining up in the ::draw implementation of their GtkTextView subclass. + As a short-term workaround, you can make the application apply a + custom theme to the text view with a transparent background. For + a proper fix, use the new ::draw_layer vfunc. + +
+ +
+ Changes in GTK+ 3.16 + + + GTK+ now includes an OpenGL rendering widget. To support GL on various + platforms, GTK+ uses libepoxy. + + + + GTK+ no longer uses gtk-update-icon-cache during its build. The + --enable-gtk2-dependency configure option has been removed. + + + + The introspection annotations for the x and y parameters of + GtkMenuPositionFunc have been corrected from 'out' to 'inout'. + If you are using such a function from language-bindings, this + may require adjustments. + + + + The lookup order for actions that are activated via keyboard + accelerators has been changed to start at the currently focused + widget. If your application is making use fo nested action groups + via gtk_widget_insert_action_group, you may want to check that + this change does not upset your accelerators. + + + + The GtkScrollable interface has gained a new vfunc, get_border, + that is used to position overshoot and undershoot indications that + are drawn over the content by GtkScrolledWindow. Unless your scrollable + has non-scrolling parts similar to treeview headers, there is no need + to implement this vfunc. + + + + The GtkSearchEntry widget has gained a number of new signals that + are emitted when certain key sequences are seen. In particular, it + now handles the Escape key and emits ::stop-search. Applications that + expect to handle Escape themselves will need to be updated. + +
+ +
+ Changes in GTK+ 3.18 + + + The GtkListBox model support that was introduced in 3.16 has been + changed to no longer call gtk_widget_show_all on rows created by + the create_widget_func. You need to manage the visibility of child + widgets yourself in your create_widget_func. + + + + The alpha component of foreground colors that are applied to + GtkCellRendererText is no longer ignored. If you don't want your + text to be translucent, use opaque colors. + +
+ +
+ Changes in GTK+ 3.20 + + + The way theming works in GTK+ has been reworked fundamentally, to + implement many more CSS features and make themes more expressive. + As a result, custom CSS that is shipped with applications and third-party + themes will need adjustments. Widgets now use element names much more + than style classes; type names are no longer used in style matching. + Every widget now documents the element names it has and the style classes + it uses. The GTK+ inspector can also help with finding this information. + + + + GTK+ now uses internal subobjects (also known as gadgets) for allocating + and drawing widget parts. Applications that subclass GTK+ widgets may see + warnings if they override the size_allocate vfunc and don't chain up. + The proper way to subclass is to chain up in size_allocate. If you do not + want to do that for some reason, you have to override the draw vfunc as + well. + + + + Several fixes for window sizing and window placement with client-side + decorations may affect applications that are saving and restoring window + sizes. The recommended best practice for this which is known to work with + client-side and server-side decorations and with older and newer versions + of GTK+ is to use gtk_window_get_size() to save window sizes and + gtk_window_set_default_size() to restore it. + See https://wiki.gnome.org/HowDoI/SaveWindowState for a detailed example. + + + + Geometry handling in GtkWindow has been removed. If you are using the + functions gtk_window_resize_to_geometry, gtk_window_set_default_geometry, + gtk_window_parse_geometry or gtk_window_set_geometry_hints, you may need + to make some changes to your code. + + + + GtkDrawingArea used to implicitly render the theme background before + calling the ::draw handler. This is no longer the case. If you rely + on having a theme-provided background, call gtk_render_background() + from your ::draw handler. + + + + The GtkFileChooser interface prerequisite changed from GtkWidget + to GObject, allowing non-widget implementations of this interface. + This is a minor change in ABI, as applications are no longer guaranteed + that a GtkFileChooser also supports all GtkWidget methods. However, all + previously existing implementations still derive from GtkWidget, so no + existing code should break. + + + + The way in which GtkLevelBar determines the offset to apply was a bit + inconsistent in the past; this has been fixed. Applications that are using + custom offsets should double-check that their levels look as expected. + +
+ -- 2.30.2